Kiro CLI：AI 驱动的终端开发助手完全指南

kiro-cli 是 Amazon 推出的终端 AI 开发助手，把 AI 能力直接带进你的命令行工作流。它不只是一个代码补全工具——它有 Code Intelligence、代码图谱分析、子 Agent 协作等一系列工具，能深度介入你从理解代码到部署的整个开发链路。这篇文章系统梳理 kiro-cli 的核心功能，以及如何配合 codegraph 等工具把开发效率真正提升一个档次。

一、kiro-cli 是什么，解决什么问题

很多开发者用过 AI 辅助编码工具，但体验往往是：写几行代码还行，稍微复杂的场景就开始胡说八道。根本原因是这类工具对代码库的理解是"碎片化"的——它只看到你当前粘贴进去的代码片段，不知道项目的整体结构、函数调用链、模块依赖关系。

kiro-cli 解决的核心问题：让 AI 真正理解你的代码库，而不是在上下文真空里工作。

它的工具层分几个维度：

• Code Intelligence：基于 AST 解析的代码语义理解，支持符号搜索、结构分析、模式匹配
• codegraph 集成：构建完整的调用图谱，追踪函数调用链和影响范围
• 子 Agent 系统：把复杂任务拆解成并行/串行的多 Agent 流水线
• 文件与终端操作：直接读写文件、执行命令，不只是"建议"，而是真的动手做

二、Code Intelligence：让 AI 真正读懂代码

这是 kiro-cli 区别于普通聊天式 AI 的核心能力。

2.1 符号搜索与精确定位

不用再手动找函数在哪里。Code Intelligence 的符号搜索基于 AST（抽象语法树）而不是文本匹配，支持模糊查询：

# 在整个项目里搜索 AuthService 相关的所有定义
search_symbols("AuthService")

# 精确查看某个符号的完整签名和源码
lookup_symbols(["loginUser", "validateToken"])

和 grep 的区别：grep 搜的是字符串，Code Intelligence 搜的是语义。搜索 getUserName 不会匹配到注释里的字符串，也不会漏掉别名导入的引用。

2.2 文件级符号概览

接手一个陌生模块，第一件事是理解它有什么：

get_document_symbols("src/auth/service.ts")

一次调用就能得到文件里所有 class、function、method、interface 的列表，不用一行行翻。对于大文件（1000 行以上），这个功能能节省大量定向时间。

2.3 AST 模式搜索与重写

这个功能是 Code Intelligence 里最强大也最容易被忽视的。它用结构化模式而不是正则表达式来匹配代码：

# 找出所有直接用 console.log 输出的地方（结构匹配，不是字符串匹配）
pattern_search(pattern="console.log($MSG)", language="typescript")

# 批量把 var 声明重写成 const
pattern_rewrite(
  pattern="var $NAME = $VALUE",
  replacement="const $NAME = $VALUE",
  language="javascript"
)

实际用途：

• 批量迁移 API（比如把旧版 fetch 写法统一改为新版）
• 查找所有未处理异常的 async 函数
• 检查是否有裸 Promise 没有 .catch()

正则表达式只能做字符串替换，AST 模式能做语义级别的批量操作。重构大型代码库时，这是节省几小时手工劳动的关键。

2.4 代码库概览生成

generate_codebase_overview(path="./src")

让 AI 扫描整个目录，生成项目结构的高层次描述。接手新项目、写文档、做技术评审前，这是最快速的热身方式。

三、codegraph：构建代码的知识图谱

Code Intelligence 给你"某个文件里有什么"，codegraph 给你"这些东西之间是什么关系"。两者配合才完整。

3.1 一次探索，理解一片区域

codegraph_explore 是最核心的入口。一个查询，返回相关符号的完整源码，按文件分组：

# 自然语言描述你想了解的区域
codegraph_explore("AuthService loginUser session token validation")

# 也可以用文件名和符号名混合查询
codegraph_explore("user-controller.ts UserController createUser")

它和直接读文件的区别是：explore 会自动把关联的代码片段聚合在一起。你不需要手动打开 5 个文件分别找函数定义——一次调用就能看到完整的上下文。

3.2 调用链追踪

理解一个 bug 或评估一个改动的影响，最需要的就是知道"谁调用了这个函数，这个函数又调用了谁"：

# 找出所有调用 processPayment 的地方
codegraph_callers("processPayment")

# 找出 processPayment 内部调用了哪些函数
codegraph_callees("processPayment")

这对于以下场景极其有用：

• 排查 bug：某个函数行为异常，先看谁在调用它，参数从哪里来
• 安全审计：敏感操作（写数据库、调外部 API）都被哪些入口触发
• 性能优化：热路径函数被调用的频率和调用来源

3.3 改动影响范围分析

在动代码之前先知道会影响什么，而不是改完之后到处救火：

# 评估修改 UserSchema 会影响哪些地方
codegraph_impact("UserSchema", depth=2)

depth 参数控制追踪的层数。depth=1 只看直接依赖，depth=3 看三层传播。做大的重构前跑一遍这个，心里有数。

3.4 符号精确定位

当你知道要看哪个具体的函数，但不确定它在哪个文件：

# 找到 validateToken 的定义、签名、调用关系
codegraph_node("validateToken", includeCode=True)

# 如果同名函数有多个，用文件名消歧义
codegraph_node("handleError", file="middleware.ts", includeCode=True)

四、文件树与搜索：精准定位，不靠猜

4.1 带元信息的文件树

codegraph_files(path="src/components", format="tree")

返回的不只是目录结构，还有每个文件的语言类型和符号数量。一眼就能看出哪个文件"内容最多"，而不是靠文件大小猜。

4.2 glob 模式文件搜索

精确找文件，不用 find 命令：

# 找所有测试文件
glob("**/*.test.ts")

# 找 src 目录下所有 TypeScript 文件
glob("src/**/*.{ts,tsx}")

4.3 语义内容搜索

知识库搜索，跨会话持久化——把代码文档、设计规范等索引进来，后续可以语义搜索：

# 把项目 API 文档索引进知识库
knowledge(command="add", name="API文档", value="./docs/api/")

# 后续搜索
knowledge(command="search", query="用户认证流程")

五、子 Agent 系统：并行处理复杂任务

这是 kiro-cli 区别于其他工具最独特的功能之一。

对于复杂任务，不是一个 Agent 串行处理，而是把它拆解成一个有向无环图（DAG），多个专门的 Agent 并行/串行协作。

5.1 基本用法

subagent(
  task="重构 auth 模块，添加 OAuth2 支持",
  stages=[
    {
      "name": "research",
      "role": "dev-agent",
      "prompt_template": "分析现有 auth 模块结构，列出需要改动的文件和接口"
    },
    {
      "name": "implement",
      "role": "dev-agent",
      "depends_on": ["research"],
      "prompt_template": "根据 research 阶段的分析，实现 OAuth2 集成"
    },
    {
      "name": "review",
      "role": "dev-agent",
      "depends_on": ["implement"],
      "prompt_template": "审查 implement 阶段的代码，检查安全性和边界情况"
    }
  ]
)

没有 depends_on 的 stage 会并行启动，有依赖的 stage 等前置完成后自动触发。

5.2 循环审查模式

对于需要反复迭代的任务（实现 → 审查 → 修改），可以加 loop_to：

stages=[
  {
    "name": "implement",
    "role": "dev-agent",
    "prompt_template": "实现功能 X"
  },
  {
    "name": "review",
    "role": "dev-agent",
    "depends_on": ["implement"],
    "prompt_template": "审查代码，如果有问题输出 NEEDS_CHANGES",
    "loop_to": {
      "target": "implement",
      "trigger": "NEEDS_CHANGES",
      "max_iterations": 3
    }
  }
]

实现和审查自动循环，直到 review 不再输出 NEEDS_CHANGES 或者达到最大迭代次数。

5.3 适合用子 Agent 的场景

• 大型重构：把分析、实现、测试、文档更新分配给不同 Agent 并行处理
• 多模块改动：多个不相关模块的修改可以真正并行
• 带审查的实现：让一个 Agent 实现，另一个 Agent 做 code review，循环直到质量达标
• 研究 + 实现分离：一个 Agent 先做技术调研，另一个拿结论来实现

六、Skills 系统：可扩展的专家能力

kiro-cli 有一套 Skills 机制，让 Agent 具备特定领域的专家能力。这些技能不是内置的，而是外部配置的 Markdown 文件，可以按需安装。

内置技能举例

开发流程类：

• brainstorming：进行任何创意工作前的头脑风暴，探索需求和设计
• writing-plans：有 spec 后、动代码前，先写实施计划
• executing-plans：按照已有的实施计划逐步执行
• test-driven-development：实现功能前先写测试

代码质量类：

• github-search-before-code：写新功能前先搜 GitHub 找参考实现
• harden：增强接口健壮性，改进错误处理和边界情况

前端设计类：

• frontend-design：生成高质量的前端界面代码
• audit：全面审计界面质量（可访问性、性能、响应式）
• animate、colorize、typeset：专项视觉优化

如何使用

在对话里直接引用技能名称，或者通过系统配置让 Agent 自动选择合适的技能。比如：

# 开始一个新功能前
"使用 brainstorming skill，帮我分析用户消息已读回执功能的需求"

# 准备动代码前
"用 writing-plans skill，基于这个需求生成实施计划"

七、实战工作流：如何组合这些工具

孤立地看每个工具价值有限，关键是把它们串成顺手的工作流。

工作流一：接手陌生代码库

1. codegraph_files() → 了解整体结构
2. generate_codebase_overview() → 生成高层次描述
3. codegraph_explore("核心业务模块名称") → 深入理解关键区域
4. codegraph_node("入口函数", includeCode=True) → 读懂启动流程

传统做法可能需要花半天浏览代码。这套流程 15-30 分钟就能建立足够的心智模型。

工作流二：定位和修复 Bug

1. 复现问题，确定出错的函数名
2. codegraph_callers("出错函数") → 找到所有调用方
3. codegraph_callees("出错函数") → 看它依赖了什么
4. codegraph_explore("相关的几个函数名") → 完整读上下文
5. 让 kiro-cli 直接修改文件并运行测试验证

工作流三：安全重构

1. codegraph_impact("要修改的符号", depth=3) → 评估影响范围
2. search_symbols("相关接口名") → 找到所有实现
3. 用 subagent 并行处理多个受影响模块
4. 每个模块改完后运行测试

工作流四：代码库级批量修改

1. pattern_search(pattern="旧写法", language="typescript") → 找出所有待修改处
2. 确认匹配结果正确
3. pattern_rewrite(pattern="旧写法", replacement="新写法") → 批量重写
4. 运行测试套件验证没有回归

八、和传统开发工具的对比

九、几个实用技巧

技巧一：探索优先，实现其次

遇到不熟悉的代码区域，先用 codegraph_explore 把相关代码一次性拉出来看，再让 AI 在这个上下文里工作。不要直接让 AI 在没有上下文的情况下修改代码。

技巧二：改动前先跑 impact 分析

养成习惯：凡是要修改公共接口、数据模型、工具函数，先跑 codegraph_impact，确认影响范围在预期之内再动手。

技巧三：用 AST 搜索代替人工审查

代码审查时，用 pattern_search 批量检查常见问题模式（比如裸 eval、SQL 字符串拼接、未处理的 Promise 等），比逐行翻代码效率高得多。

技巧四：子 Agent 做研究，主 Agent 做实现

复杂功能实现前，先起一个子 Agent 专门做技术调研（搜 GitHub、分析竞品实现、评估方案 tradeoff），把结论拿回来，主 Agent 再在有充分信息的基础上实现。

技巧五：让知识库记住项目规范

把项目的编码规范、架构决策记录（ADR）、API 约定等索引进知识库，后续每次让 AI 写代码时让它先搜知识库，确保输出符合项目规范。

十、总结

kiro-cli 不是"更聪明的代码补全"，而是一套以代码理解为基础的开发协作系统。核心价值链是：

理解代码库（codegraph） → 精准搜索（Code Intelligence） → 安全修改（impact 分析） → 高效实现（子 Agent 并行）

每个工具单独用都有价值，但真正发挥威力是在你把它们串成工作流之后。理解代码的成本降下来，影响范围变得可见，复杂任务可以并行——这才是开发效率提升的实质。

工具只是手段，关键还是你对要解决的问题有清晰的定义。AI 工具链越强，对"想清楚再动手"这件事的要求反而越高。